package it.traveldream.beans;

import it.traveldream.dto.ExcursionDTO;
import it.traveldream.dto.HotelDTO;
import it.traveldream.dto.LocationDTO;
import it.traveldream.dto.TPDTO;
import it.traveldream.dto.TransportMeanDTO;
import it.traveldream.exceptions.InvalidProductException;
import it.traveldream.exceptions.InvalidTPException;
import it.traveldream.exceptions.LocationNotFoundException;
import it.traveldream.exceptions.ProductNotFoundException;
import it.traveldream.exceptions.TPNotFoundException;

import java.util.List;

import javax.ejb.Local;

/**
 * 
 * @author Flavio Ferrara
 * <p>
 * PackageManagerInterface declares and describes available functions that the client can call
 * in order to handle travel packages.
 * 
 * This interface will be implemented by one or more Enterprise Java Beans.
 */

@Local
public interface PackageManagerInterface {
	
	/**
	 * Returns a list containing all travel packages existing for a specific location.
	 * @param location The location to be searched for.
	 * @return List of travel packages.
	 * @throws LocationNotFoundException
	 */
	public List<TPDTO> getTPsByLocation(LocationDTO location) throws LocationNotFoundException;
	
	/**
	 * Return information about a specific travel package.
	 * The argument must contain a valid value for product ID field.
	 * @param The travel package to be searched for.
	 * @return A representation of the travel package.
	 * @throws TPNotFoundException
	 */
	public TPDTO getTP(TPDTO travelPackage) throws TPNotFoundException;
	
	/**
	 * Records in Persistence tier information about a travel package.
	 * The argument must contain valid values for fields:
	 * <ul>
	 * <li> transportMean
	 * <li> hotel
	 * </ul>
	 * The client is not required to provide an ID as argument. If the argument 
	 * contains any value, it will be ignored and replaced with an auto-generated one.
	 * @param travelPackage The TP to be recorded.
	 * @return The TP containing generated ID.
	 */
	public TPDTO saveTP(TPDTO travelPackage) throws ProductNotFoundException, InvalidTPException;
	
	/**
	 * Updates in Persistence tier information about an existing travel package.
	 * The argument must contain a valid value for product ID field.
	 * @param travelPackage The travel package to be updated.
	 * @throws TPNotFoundException
	 * @throws InvalidTPException 
	 * @throws InvalidProductException
	 */
	public void updateTP(TPDTO travelPackage) throws TPNotFoundException, ProductNotFoundException, InvalidTPException;
	
	/**
	 * Deletes from Persistence tier an existing travel package.
	 * The argument must contain a valid value for product ID field.
	 * @param travelPackage The travel package to be deleted.
	 * @throws TPNotFoundException
	 */
	public void deleteTP(TPDTO travelPackage) throws TPNotFoundException;
	
	/**
	 * Returns a list of transport means which can be inserted in a specific travel package.
	 * @param travelPackage The travel package which the means are related to.
	 * @return List of transport means
	 * @throws TPNotFoundException
	 */
	public List<TransportMeanDTO> getAlternativeMeans(TPDTO travelPackage) throws TPNotFoundException;
	
	/**
	 * Returns a list of hotels which can be inserted in a specific travel package.
	 * @param travelPackage The travel package which the hotels are related to.
	 * @return List of hotels
	 * @throws TPNotFoundException
	 */
	public List<HotelDTO> getAlternativeHotels(TPDTO travelPackage) throws TPNotFoundException;
	
	/**
	 * Returns a list of excursions which can be inserted in a specific travel package.
	 * @param travelPackage The travel package which the excursions are related to.
	 * @return List of excursions
	 * @throws TPNotFoundException
	 */
	public List<ExcursionDTO> getAlternativeExcursions(TPDTO travelPackage) throws TPNotFoundException;
	
	/**
	 * Updates an existing travel package by replacing its transport mean with the 
	 * specified one
	 * @param travelPackage The travel package
	 * @param mean The transport mean that will be inserted into the package
	 * @throws TPNotFoundException
	 * @throws ProductNotFoundException
	 */
	public void setMean(TPDTO travelPackage, TransportMeanDTO mean) throws TPNotFoundException, ProductNotFoundException;
	
	/**
	 * Updates an existing travel package by replacing its hotel with the 
	 * specified one
	 * @param travelPackage The travel package
	 * @param hotel The hotel that will be inserted into the package
	 * @throws TPNotFoundException
	 * @throws ProductNotFoundException
	 */
	public void setHotel(TPDTO travelPackage, HotelDTO hotel) throws TPNotFoundException, ProductNotFoundException;
	
	/**
	 * Updates an existing travel package by adding an excursion to its list
	 * @param travelPackage The travel package
	 * @param excursion The excursion that will be inserted into the package
	 * @throws TPNotFoundException
	 * @throws ProductNotFoundException
	 */
	public void addExcursion(TPDTO travelPackage, ExcursionDTO excursion) throws TPNotFoundException, ProductNotFoundException;
	
	/**
	 * Updates an existing travel package by removing an excursion to its list
	 * @param travelPackage The travel package
	 * @param excursion The excursion that will be removed from the package
	 * @throws TPNotFoundException
	 * @throws ProductNotFoundException
	 */
	public void removeExcursion(TPDTO travelPackage, ExcursionDTO excursion) throws TPNotFoundException, ProductNotFoundException;
}
